feat: ship per-arch standalone binaries on each release by ja-818 · Pull Request #73 · stripe/link-cli

ja-818 · 2026-05-04T22:48:02Z

Summary

Adds a release workflow that attaches single-file standalone link-cli binaries to every GitHub Release, plus a manifest.json with sha256 checksums and per-target download URLs. Targets: darwin-arm64, darwin-x64, linux-x64, windows-x64.

Motivation

We're shipping Houston (a desktop platform for non-technical founders to run AI agents) with Link as a first-class payments surface. Houston bundles three CLIs today (codex, composio, claude-code); for each we download a signed binary from upstream, sha256-verify, sign + notarize alongside our .app, and stage it into Contents/Resources/bin/. That works well because each upstream ships per-arch standalone binaries.

link-cli only ships on npm. Bundling a non-Node binary today means owning a bun build --compile (or pkg) pipeline per consumer, which means every consumer hitting the same packaging edges (the react-devtools-core resolution issue under ink, update-notifier external handling, viem's WASM + dynamic imports). Solving it once upstream is a much smaller surface than every agent platform doing it independently.

Tracking issue with full context: #72.

What this PR does

scripts/build-binary.ts: invokes Bun.build against the existing packages/cli/dist/cli.js entrypoint, with a tiny in-process plugin that stubs two optional deps (react-devtools-core is dynamically loaded by ink only when DEV=true; update-notifier is already external in tsup.config.ts). Output: dist-bin/link-cli-<target>[.exe].
scripts/generate-manifest.ts: walks dist-bin/, sha256s every binary, emits manifest.json with version, generated_at, and per-target { file, sha256, url }.
.github/workflows/release-binaries.yml: triggers on release.published (the event changesets/action fires on every npm publish). On a single Ubuntu runner, builds all four targets via Bun cross-compile, generates the manifest, and uploads everything to the existing release via gh release upload. workflow_dispatch is provided for manual rebuilds against an existing tag.
README.md: short "Standalone binaries" section under Installation pointing at the latest release + the manifest URL pattern.
.gitignore: adds dist-bin/.

Verification

Run locally on macOS arm64 (Bun 1.3.10, Node 22, pnpm 10.32):

pnpm install --frozen-lockfile
pnpm turbo run build
for t in darwin-arm64 darwin-x64 linux-x64 windows-x64; do
  bun run scripts/build-binary.ts $t
done
bun run scripts/generate-manifest.ts 0.4.2

Result on darwin-arm64 host:

All four targets compile; total time < 10s after pnpm turbo run build.
dist-bin/link-cli-darwin-arm64 --help and --version work.
dist-bin/link-cli-darwin-arm64 mpp decode --challenge 'Payment id="ch_001", realm="merchant.example", method="stripe", intent="charge", request="..."' runs the viem-backed challenge decoder successfully (validation reaches the per-field "amount: missing" check, which is the expected behavior for an incomplete test challenge).
Sizes (minified): darwin-arm64 60 MB, darwin-x64 64 MB, linux-x64 101 MB, windows-x64 111 MB. Linux/Windows are heavier because Bun ships more runtime polyfills for non-host targets.

CI gauntlet on this branch passes locally:

pnpm biome check . — clean (96 files)
pnpm turbo run typecheck — pass
pnpm turbo run test — 100/100 pass
pnpm turbo run build — pass

Notes

I pinned Bun to 1.3.10 in the workflow to keep release outputs reproducible. Happy to change that to latest or whatever your team prefers.
The script uses // @ts-expect-error on one line because the compile option is supported by Bun.build at runtime but not yet in the public TypeScript types.
Stub plugin replaces module contents, not the import path, so the bundled output has no leftover references to either optional dep on disk.
I haven't touched release.yml — the existing changesets-driven flow is unchanged. This new workflow is fully additive and runs after the release event the existing flow already produces.
I'll sign the CLA on first comment.

Future work (not in this PR)

Lazy-load viem inside mpp decode so the static bundle is smaller for non-MPP users (mentioned in the tracking issue).
Linux arm64 + Windows arm64 if there's demand. Bun supports both targets; happy to add in a follow-up.

🤖 Co-authored with Claude Code.

cla-assistant · 2026-05-04T22:48:20Z

All committers have signed the CLA.

Adds a release-binaries workflow that produces single-file standalone link-cli binaries for darwin-arm64, darwin-x64, linux-x64, and windows-x64 every time a GitHub Release is published, plus a manifest.json with sha256 checksums and download URLs. Motivation: agent platforms and desktop apps that want to bundle link-cli currently have to build their own binaries from the npm package, which means owning a CI pipeline that compiles ink + viem + update-notifier into a single executable. Shipping binaries upstream lets downstream consumers pin against a manifest URL the same way they pin any other vendored CLI (codex, claude-code, etc). How it works: - scripts/build-binary.ts runs bun build --compile against the existing packages/cli/dist/cli.js entrypoint. A small plugin stubs two optional deps that ink and update-notifier reference but that are not needed at runtime in a bundled context (react-devtools-core only loads when DEV=true; update-notifier is already external in tsup). - scripts/generate-manifest.ts emits dist-bin/manifest.json with version, generated_at, and per-target { file, sha256, url }. - .github/workflows/release-binaries.yml triggers on release.published (changesets/action publishes a GH release on every npm release), builds all four targets in parallel inside a single Ubuntu runner via Bun cross-compile, and attaches the binaries + manifest to the release. Verified locally: each binary runs --help, --version, and exercises the viem-dependent mpp decode path successfully on darwin-arm64. Sizes (minified): darwin-arm64 60 MB, darwin-x64 64 MB, linux-x64 101 MB, windows-x64 111 MB. Linux/Windows are heavier because Bun ships more runtime polyfills for non-host targets.

ja-818 · 2026-05-05T14:10:47Z

Force-pushed with the correct git author email so the commit links to my GitHub account. Going to sign the CLA now.

danhill-stripe · 2026-05-05T23:39:33Z

+          done
+
+      - name: Generate manifest
+        run: bun run scripts/generate-manifest.ts "${{ steps.tag.outputs.version }}"


doesn't this script need two params?

Good catch — second arg was an optional URL override but nothing ever passed it, so it was dead flexibility. Removed in 3ee1633: script now takes one required version arg, with the GitHub releases URL hardcoded inline.

The script's second arg was an optional override for the GitHub releases download URL. Nothing in this workflow ever passes it, so the override is dead flexibility. Hardcoding the URL pattern simplifies the call site and matches the script's actual usage.

raubrey-stripe

Left some feedback @ja-818! Hopefully some quick hygiene.

Also, I'm curious how this will show up for your end customers, but because we are not signing our binaries in any way here in a sort of "apple approved" way, macOS Gatekeeper will quarantine the downloaded binary.. I'm not exactly sure how this will show up to end customers for you when bundled in Houston, but you can see the experience in another one of our products (purl) that bundles binaries: https://github.com/stripe/purl/releases/tag/v0.2.7

raubrey-stripe · 2026-05-09T13:37:40Z

+        run: |
+          TAG="${{ github.event.release.tag_name || github.event.inputs.release_tag }}"
+          # Strip the @stripe/link-cli@ prefix changesets uses, leaving "0.4.2"
+          VERSION="${TAG##*@}"
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"


run: steps interpolate ${{ }} expressions directly into shell commands. Per https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#understanding-the-risk-of-script-injections, these should use intermediate env: vars to avoid shell injection via crafted tag names.

Suggested change

run: |

TAG="${{ github.event.release.tag_name || github.event.inputs.release_tag }}"

# Strip the @stripe/link-cli@ prefix changesets uses, leaving "0.4.2"

VERSION="${TAG##*@}"

echo "tag=$TAG" >> "$GITHUB_OUTPUT"

env:

TAG: ${{ github.event.release.tag_name || github.event.inputs.release_tag }}

run: |

# Strip the @stripe/link-cli@ prefix changesets uses, leaving "0.4.2"

VERSION="${TAG##*@}"

echo "tag=$TAG" >> "$GITHUB_OUTPUT"

raubrey-stripe · 2026-05-09T13:40:45Z

+          done
+
+      - name: Generate manifest
+        run: bun run scripts/generate-manifest.ts "${{ steps.tag.outputs.version }}"


Same feedback as above:

Suggested change

run: bun run scripts/generate-manifest.ts "${{ steps.tag.outputs.version }}"

env:

VERSION: ${{ steps.tag.outputs.version }}

run: bun run scripts/generate-manifest.ts "$VERSION"

raubrey-stripe · 2026-05-09T13:41:32Z

+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release upload "${{ steps.tag.outputs.tag }}" \


Same, replace with RELEASE_TAG: ${{ steps.tag.outputs.tag }} in env and "$RELEASE_TAG" here

raubrey-stripe · 2026-05-09T13:46:37Z

+await Bun.build({
+  entrypoints: ['./packages/cli/dist/cli.js'],
+  // @ts-expect-error compile is a Bun.build option but not in the public types yet
+  compile: { target: flag, outfile },
+  plugins: [stubPlugin],
+  minify: true,
+});


Bun compiled executables auto-load .env from the current working directory. This means a malicious .env in the working directory could override LINK_API_BASE_URL or LINK_AUTH_BASE_URL to redirect API calls.

We need to disable this behavior; we could wrap the entry point here in a small wrapper that disables env pick up i.e. Can you give this a shot and confirm that a local .env cannot be used to set env variables?

entrypoints: ['./scripts/binary.ts'],

// ./scripts/binary.ts // Disables Bun's automatic .env loading to prevent a malicious .env file in process.env.BUN_CONFIG_NO_DOTENV = '1; import '../packages/cli/dist/cli.js';

raubrey-stripe · 2026-05-09T13:48:57Z

+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ steps.tag.outputs.tag }}
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: '1.3.10'
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: pnpm


Can you pin these actions to a specific SHA? That's considered best practice in a workflow like this - I think it'd be

Suggested change

- uses: actions/checkout@v4

with:

ref: ${{ steps.tag.outputs.tag }}

- uses: oven-sh/setup-bun@v2

with:

bun-version: '1.3.10'

- uses: pnpm/action-setup@v4

- uses: actions/setup-node@v4

with:

node-version: 20

cache: pnpm

- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4

with:

ref: ${{ steps.tag.outputs.tag }}

- uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2

with:

bun-version: '1.3.10'

- uses: pnpm/action-setup@f40ffcd9367d9f12939873eb1018b921a783ffaa # v4

- uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4

with:

node-version: 20

cache: pnpm

ja-818 requested a review from a team as a code owner May 4, 2026 22:48

ja-818 mentioned this pull request May 4, 2026

Platform integration: shipping Houston with Link, four upstream asks (per-arch binaries, manifest URL, viem isolation, SKILL versioning) #72

Open

ja-818 force-pushed the add-binary-releases branch from 17e5b3f to 23fdf0a Compare May 5, 2026 14:10

danhill-stripe reviewed May 5, 2026

View reviewed changes

raubrey-stripe reviewed May 9, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: ship per-arch standalone binaries on each release#73

feat: ship per-arch standalone binaries on each release#73
ja-818 wants to merge 2 commits intostripe:mainfrom
gethouston:add-binary-releases

ja-818 commented May 4, 2026

Uh oh!

cla-assistant Bot commented May 4, 2026 •

edited

Loading

Uh oh!

ja-818 commented May 5, 2026

Uh oh!

danhill-stripe May 5, 2026

Uh oh!

ja-818 May 6, 2026

Uh oh!

raubrey-stripe left a comment

Uh oh!

raubrey-stripe May 9, 2026

Uh oh!

raubrey-stripe May 9, 2026

Uh oh!

raubrey-stripe May 9, 2026

Uh oh!

raubrey-stripe May 9, 2026

Uh oh!

raubrey-stripe May 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

-        run: bun run scripts/generate-manifest.ts "${{ steps.tag.outputs.version }}"
+      env:
+          VERSION: ${{ steps.tag.outputs.version }}
+        run: bun run scripts/generate-manifest.ts "$VERSION"

Conversation

ja-818 commented May 4, 2026

Summary

Motivation

What this PR does

Verification

Notes

Future work (not in this PR)

Uh oh!

cla-assistant Bot commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ja-818 commented May 5, 2026

Uh oh!

danhill-stripe May 5, 2026

Choose a reason for hiding this comment

Uh oh!

ja-818 May 6, 2026

Choose a reason for hiding this comment

Uh oh!

raubrey-stripe left a comment

Choose a reason for hiding this comment

Uh oh!

raubrey-stripe May 9, 2026

Choose a reason for hiding this comment

Uh oh!

raubrey-stripe May 9, 2026

Choose a reason for hiding this comment

Uh oh!

raubrey-stripe May 9, 2026

Choose a reason for hiding this comment

Uh oh!

raubrey-stripe May 9, 2026

Choose a reason for hiding this comment

Uh oh!

raubrey-stripe May 9, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

cla-assistant Bot commented May 4, 2026 •

edited

Loading